3.4.1 Theorem and Axiom Environments

Suppose you are using \newtheorem in LaTeX in order to define two new environments, theorem and axiom

\newtheorem{axiom}{Axiom}
\newtheorem{theorem}{Theorem}

to be used like this:

\begin{axiom}
\label{ax:first}
  ....
\end{axiom}

So we need to tell RefTeX that theorem and axiom are new labeled environments which define their own label categories. We can either use Lisp to do this (e.g., in .emacs) or use the custom library. With Lisp it would look like this

(setq reftex-label-alist
   '(("axiom"   ?a "ax:"  "~\\ref{%s}" nil ("axiom"   "ax.") -2)
     ("theorem" ?h "thr:" "~\\ref{%s}" t   ("theorem" "th.") -3)))

The type indicator characters ?a and ?h are used for prompts when RefTeX queries for a label type. ?h was chosen for theorem since ?t is already taken by table. Note that also ?s, ?f, ?e, ?i, ?n are already used for standard environments.

The labels for Axioms and Theorems will have the prefixes ‘ax:’ and ‘thr:’, respectively. See AUCTeX, for information on how AUCTeX can use RefTeX to automatically create labels when a new environment is inserted into a buffer. Additionally, the following needs to be added to one’s .emacs file before AUCTeX will automatically create labels for the new environments.

(add-hook 'LaTeX-mode-hook
   (lambda ()
     (LaTeX-add-environments
       '("axiom" LaTeX-env-label)
       '("theorem" LaTeX-env-label))))

The ‘~\ref{%s}’ is a format string indicating how to insert references to these labels.

The next item indicates how to grab context of the label definition.

• - t means to get it from a default location (from the beginning of a \macro or after the \begin statement). t is not a good choice for eqnarray and similar environments.
• - nil means to use the text right after the label definition.
• - For more complex ways of getting context, see the variable reftex-label-alist (Options - Defining Label Environments).

The following list of strings is used to guess the correct label type from the word before point when creating a reference. For example if you write: ‘As we have shown in Theorem’ and then press C-c ), RefTeX will know that you are looking for a theorem label and restrict the menu to only these labels without even asking.

The final item in each entry is the level at which the environment should produce entries in the table of context buffer. If the number is positive, the environment will produce numbered entries (like \section), if it is negative the entries will be unnumbered (like \section*). Use this only for environments which structure the document similar to sectioning commands. For everything else, omit the item.

To do the same configuration with customize, you need to click on the [INS] button twice to create two templates and fill them in like this:

Reftex Label Alist: [Hide]
[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: axiom
            Type specification    : [Value Menu] Char  : a
            Label prefix string   : [Value Menu] String: ax:
            Label reference format: [Value Menu] String: ~\ref{%s}
            Context method        : [Value Menu] After label
            Magic words:
              [INS] [DEL] String: axiom
              [INS] [DEL] String: ax.
              [INS]
            [X] Make TOC entry    : [Value Menu] Level: -2
[INS] [DEL] Package or Detailed   : [Value Menu] Detailed:
            Environment or \macro : [Value Menu] String: theorem
            Type specification    : [Value Menu] Char  : h
            Label prefix string   : [Value Menu] String: thr:
            Label reference format: [Value Menu] String: ~\ref{%s}
            Context method        : [Value Menu] Default position
            Magic words:
              [INS] [DEL] String: theorem
              [INS] [DEL] String: theor.
              [INS] [DEL] String: th.
              [INS]
            [X] Make TOC entry    : [Value Menu] Level: -3

Depending on how you would like the label insertion and selection for the new environments to work, you might want to add the letters ‘a’ and ‘h’ to some of the flags in the variables reftex-insert-label-flags (see Options - Creating Labels) and reftex-label-menu-flags (see Options - Referencing Labels).